---
title: Download by tracking id
summary: Returns a previously produced output document only when its tracked status is Succeeded and an output path is recorded.
status: draft
owner: Not determined from source
last_reviewed: 2026-09-17
library: PdfAPI
reference_type: embedded
operation_id: OP-DOWNLOAD-BY-TRACKING-ID
trigger: Client requests GET v1/legacy/download/{trackingId}
---

# OP-DOWNLOAD-BY-TRACKING-ID: Download by tracking id

Looks up a tracking record by id and returns the associated output document only when the tracked status is `Succeeded` and an output file path is recorded.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-DOWNLOAD-BY-TRACKING-ID |
| **Trigger** | Client requests `GET v1/legacy/download/{trackingId}` |
| **Entry endpoint** | [`GET v1/legacy/download/{trackingId}`](../endpoints/legacy-controller.md#get-v1%2Flegacy%2Fdownload%2F%7Btrackingid%7D) |
| **Owning component** | `LegacyController.Download(long)` → `PdfTrackingService.DownloadByTrackingId(long)` |
| **Inputs** | `trackingId` route segment |
| **Outputs** | `PdfResult` (`Status`, `Message`, `Document`) |
| **Failure response** | Caught exceptions are logged and returned as `Ok(new PdfResult(message))` — HTTP `200`; a missing/incomplete tracking record also returns `200` with a failure `PdfResult` |

## Steps

1. The action wraps the call in `try`/`catch` ([BR-PDFAPI-017](../business-rules.md#br-pdfapi-017-processing-failures-return-200-with-a-pdfresult)).
   - On any exception: `_logService.LogException("pdfapi", "Download", "<detail>", ex)`, then `Ok(new PdfResult(ex.Message))` — HTTP `200`.
2. `PdfTrackingService.DownloadByTrackingId` reads the `PDFTracking` row by `Id` ([data model](../data-model.md#pdftracking-properties-observed-in-use)).
   - If no row is found: an explanatory failure `PdfResult` is returned — HTTP `200`.
3. If the row's `StatusCode` is `Succeeded` and `OutputFilePath` is non-null, the file is loaded from disk into a `Document` and returned ([BR-PDFAPI-013](../business-rules.md#br-pdfapi-013-download-requires-succeeded-status-and-output-path)).
   - Otherwise: an explanatory failure `PdfResult` (e.g. still processing, failed, or no output path) is returned — HTTP `200`.
4. The controller returns `Ok(result)`.

## Process flow

The following diagram shows the tracking-lookup and download-decision sequence.

```mermaid
flowchart TD
    A["GET v1/legacy/download/trackingId"] --> B["Read PDFTracking by Id"]
    B -->|Not found| C["Failure PdfResult, 200"]
    B -->|Found| D{"Status Succeeded and<br>OutputFilePath set?"}
    D -->|Yes| E["Load document from disk,<br>return PdfResult with Document"]
    D -->|No| F["Explanatory failure PdfResult, 200"]
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | `IUnitOfWorkFactory("oracle")`, `InstancePerRequest` (read-only) |
| Commit point | No write — read-only `Query()` inside `Begin()`/`Commit()` |
| Records written | None |
| Downstream calls | None |
| Repeat-call behavior | Idempotent — repeated calls return the same result while the tracking record is unchanged |

## Logging

| Surface | Written content |
| --- | --- |
| `ILogService.LogException` | `"pdfapi"`, `"Download"`, and exception detail, on any caught failure |

## Error handling

- Tracking record not found, or status not `Succeeded`, or `OutputFilePath` null: not an exception — an explanatory failure `PdfResult` with HTTP `200` ([BR-PDFAPI-013](../business-rules.md#br-pdfapi-013-download-requires-succeeded-status-and-output-path)).
- Any other exception (e.g. `trackingId` fails to parse as `long` — route does not match): produces the framework's default routing-failure response, not this operation's envelope.

## Related documentation
- [API index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Endpoints](../endpoints.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Data model](../data-model.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

## Sources
- PdfAPI\Controllers\v1\LegacyController.cs
- PdfAPI\Services\PdfTrackingService.cs
- PdfAPI.Core\PdfResult.cs